Allocate

Allocate
Header:	Files.h		Carbon status:	Supported

Allocates additional blocks to an open file.

OSErr Allocate (
    SInt16 refNum, 
    SInt32 *count
);

refNum: The file reference number of an open file.
count: On input, a pointer to the number of additional bytes to allocate to the file; on output, a pointer to the number of bytes actually allocated, rounded up to the nearest multiple of the allocation block size.

function result: A result code.

DISCUSSION

The Allocate function adds the specified number of bytes to the specified file and sets the physical end-of-file to 1 byte beyond the last block allocated. If there isn’t enough empty space on the volume to satisfy the allocation request, Allocate allocates the rest of the space on the volume and returns dskFulErr as its function result.

The Allocate function always attempts to allocate contiguous blocks. If the total number of requested bytes is unavailable, Allocate allocates whatever space, contiguous or not, is available. To force the allocation of the entire requested space as a contiguous piece, call AllocContig instead.

The File Manager automatically allocates file blocks if you move the logical end-of-file past the physical end-of-file, and it automatically deallocates unneeded blocks from a file if you move the logical end-of-file to a position more than one allocation block before the current physical end-of-file. Consequently, you do not in general need to be concerned with allocating or deallocating file blocks. However, you can improve file block contiguity if you use the Allocate or AllocContig function to preallocate file blocks. This is most useful if you know in advance how big a file is likely to become.

When the File Manager allocates (or deallocates) file blocks automatically, it always adds (or removes) blocks in clumps. The Allocate function allows you to add blocks in allocation blocks, which may be smaller than clumps.

The Allocate function is not supported by AppleShare volumes. Instead, use SetEOF or PBSetEOFAsync or PBSetEOFSync to extend a file by setting the end-of-file.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.